RESTful API 完整规范

一、核心设计思想

REST（Representational State Transfer，表述性状态转移），核心：用 HTTP 动词表达操作，URL 代表资源，无状态，返回统一资源表述

1. 一切皆资源，URL 只描述资源，不描述动作
2. 使用标准 HTTP Method 区分增删改查
3. 无状态：每次请求携带全部信息，服务端不存会话
4. 统一返回格式、状态码、命名规范

二、URL 资源命名规范

1. 名词复数（核心）

资源统一用复数名词，不用动词

# 正确
GET    /users        获取所有用户
GET    /users/123    获取id=123的用户
POST   /users        创建用户
PUT    /users/123    全量更新用户
DELETE /users/123    删除用户

# 错误（含动词）
/getUsers
/deleteUser/123

2. 资源层级关联（父子资源）

用 / 表示从属关系

GET /users/100/orders       # 100号用户的所有订单
GET /users/100/orders/200   # 100用户下200号订单

3. 命名规则

• 小写英文，

  横线 - 分隔

  ，禁止下划线、驼峰

  /user-address  ✅
  /userAddress /user_address ❌

• 过滤特殊字符，不用中文、空格

• 版本号放 URL 头部（两种主流方案）

  # 方案1（推荐）
  /api/v1/users
  # 方案2（Header）
  Header: Accept: application/vnd.xxx.v1+json

• 全局统一前缀 /api 区分前端页面接口

4. 分页、筛选、排序用 Query 参数

不要写进路径

# 正确
GET /users?page=1&size=10&sort=createTime,desc&status=enable

# 错误
/users/page/1/size/10

三、HTTP Method 标准语义（最关键）

Method	语义	操作说明
GET	查询资源	只读，无副作用，可缓存
POST	创建资源	新增，服务端生成唯一 ID
PUT	全量更新	完整替换资源，必填所有字段
PATCH	局部更新	只传修改字段，增量更新
DELETE	删除资源	移除指定资源

示例对比

# 创建用户
POST /users  body:{name:"张三"}

# 完整覆盖更新用户123
PUT /users/123 body:{name:"新名字",age:20,...全部字段}

# 只修改年龄
PATCH /users/123 body:{age:22}

# 删除
DELETE /users/123

四、HTTP 状态码规范

2xx 成功

• 200 OK：GET/PUT/PATCH 查询、更新成功
• 201 Created：POST 创建资源成功（返回资源地址 Location）
• 204 No Content：DELETE 删除成功，无返回体

3xx 重定向（较少用）

• 304 Not Modified：缓存未过期

4xx 客户端错误

• 400 Bad Request：参数格式错误、请求体非法
• 401 Unauthorized：未登录 /token 失效
• 403 Forbidden：已登录，但无操作权限
• 404 Not Found：资源不存在
• 405 Method Not Allowed：接口不支持该请求方式（如对 GET 接口发 POST）
• 409 Conflict：资源冲突（重复创建唯一值）
• 422 Unprocessable Entity：参数校验失败（字段非法、长度不足）

5xx 服务端错误

• 500 Internal Server Error：服务器未知异常
• 503 Service Unavailable：服务停机 / 限流

五、统一返回 JSON 格式（行业通用模板）

成功返回

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "username": "test"
  }
}

分页列表

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "records": [],
    "total": 135,
    "page": 1,
    "size": 10
  }
}

失败返回

{
  "code": 422,
  "msg": "用户名不能为空",
  "data": null
}

约定：

• code：业务码，和 HTTP 状态码保持对应
• msg：人类可读提示文案
• data：业务数据，无数据时返回 null，不省略字段

六、请求头规范

1. 请求数据格式统一 JSON

Content-Type: application/json

1. 身份认证

Authorization: Bearer {token}

1. 客户端标识

User-Agent: xxx-app/1.0

七、高级场景规范

1. 复杂动作（无对应资源动词）

不要把动作放 URL，两种方案：

• 方案 1：用资源状态字段 + PATCH

  PATCH /orders/100 {status:"cancel"}

• 方案 2：新增动作子资源 POST

  POST /orders/100/cancel

2. 文件上传

• 单文件：POST /upload，Content-Type: multipart/form-data
• 资源关联上传：POST /users/100/avatar

3. 搜索

统一用 GET + query，不新建 /search 路径

GET /goods?keyword=手机

八、禁止的不规范写法

1. URL 包含动词：/addUser /updateUser
2. GET 请求做修改 / 删除操作（安全风险，缓存、爬虫会误操作）
3. 驼峰、下划线、中文路径
4. 接口同时返回 HTML/XML/JSON，强制统一 JSON
5. 不区分 PUT/PATCH，全部用 PUT 局部更新
6. 用 200 代替 201、204、4xx、5xx，所有请求统一返回 200

九、简单示例全套接口（用户模块）

# 查询列表
GET    /api/v1/users?page=1&size=10
# 单条查询
GET    /api/v1/users/1
# 创建
POST   /api/v1/users
# 全量更新
PUT    /api/v1/users/1
# 局部更新
PATCH  /api/v1/users/1
# 删除
DELETE /api/v1/users/1
# 用户订单
GET    /api/v1/users/1/orders